
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>Stratified Plume Model User’s Guide &#8212; Texas A&amp;M Oil spill / Outfall Calculator 2.1.0 documentation</title>
    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script src="../_static/jquery.js"></script>
    <script src="../_static/underscore.js"></script>
    <script src="../_static/doctools.js"></script>
    <script src="../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="lake_bub" href="../scripts/spm/lake_bub.html" />
    <link rel="prev" title="seep_bubble" href="../scripts/sbm/seep_bubble.html" />
   
  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <div class="section" id="stratified-plume-model-user-s-guide">
<h1>Stratified Plume Model User’s Guide<a class="headerlink" href="#stratified-plume-model-user-s-guide" title="Permalink to this headline">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Release</dt>
<dd class="field-odd"><p>2.1</p>
</dd>
<dt class="field-even">Date</dt>
<dd class="field-even"><p>Jun 05, 2020</p>
</dd>
</dl>
<div class="section" id="scripts">
<h2>Scripts<a class="headerlink" href="#scripts" title="Permalink to this headline">¶</a></h2>
<p>The class objects and method functions defined in the <cite>stratified_plume_model</cite>
module provide a flexible structure to handle simulations of a multiphase
plume from a discrete source. The examples detailed below show how
to set up and run <cite>stratified_plume_model</cite> simulations. Further examples are
presented in the following scripts distributed in the <code class="docutils literal notranslate"><span class="pre">./bin/spm</span></code> directory
with the source code.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../scripts/spm/lake_bub.html">lake_bub</a></li>
<li class="toctree-l1"><a class="reference internal" href="../scripts/spm/lake_part.html">lake_part</a></li>
<li class="toctree-l1"><a class="reference internal" href="../scripts/spm/spm_blowout_sim.html">spm_blowout_sim</a></li>
<li class="toctree-l1"><a class="reference internal" href="../scripts/spm/spm_file_io.html">sbm_file_io</a></li>
</ul>
</div>
</div>
<div class="section" id="notebooks">
<h2>Notebooks<a class="headerlink" href="#notebooks" title="Permalink to this headline">¶</a></h2>
<p>An IPython Notebook for modeling a submarine blowout has been created and is
available in the <code class="docutils literal notranslate"><span class="pre">./notebooks</span></code> directory of the source code distribution.
To open the notebook, execute the following command at a command prompt for
within the <code class="docutils literal notranslate"><span class="pre">./notebooks</span></code> directory:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ipython</span> <span class="n">notebook</span> <span class="o">--</span><span class="n">pylab</span> <span class="n">inline</span>
</pre></div>
</div>
<p>The notebook will open in a web browser.  Click on the <code class="docutils literal notranslate"><span class="pre">Blowout_sim</span></code> link
on the IPy Ipython Dashboard.  This will open the Submarine Accidental Oil
Spill Calculator IPy Notebook.  Edit the executable lines that are indicated
by comments that begin as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Enter...</span>
</pre></div>
</div>
<p>You can run the simulation by clicking <code class="docutils literal notranslate"><span class="pre">Run</span> <span class="pre">All</span></code> from the left task panes.
You may also rename the notebook and save using the toolbar at the top of
the page.</p>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<p>This example illustrates the tasks necessary to setup, run, save, and
post-process simulations using the <cite>stratified_plume_model</cite> module. Before
running these examples, be sure to install the <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code> package and run
all of the tests in the <code class="docutils literal notranslate"><span class="pre">./test</span></code> directory.  The commands below should
be executed in an IPython session.  Start IPython by executing:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ipython</span> <span class="o">--</span><span class="n">pylab</span>
</pre></div>
</div>
<p>at the command prompt.  The <code class="docutils literal notranslate"><span class="pre">--pylab</span></code> flag is needed to get the correct
behavior of the output plots.</p>
<p>The first step in any spill simulation is to define the ambient CTD data. The
<code class="docutils literal notranslate"><span class="pre">TAMOC</span></code> module <cite>ambient</cite> provides the tools needed to read in CTD data from
text files and organize it into the netCDF files used by the <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code>
simulation modules. Examples of how to do this are provided in the
<code class="docutils literal notranslate"><span class="pre">./bin/ambient</span></code> directory of the TAMOC distribution. Here, we use the CTD
data created by the <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code> test files and stored in the <code class="docutils literal notranslate"><span class="pre">./test/output</span></code>
directory. Open a CTD file as follows (path names in this tutorial are from
any subdirectory of the <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code> source distribution, e.g.,
<code class="docutils literal notranslate"><span class="pre">./notebooks</span></code>):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_file</span> <span class="o">=</span> <span class="s1">&#39;../test/output/test_BM54.nc&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ctd</span> <span class="o">=</span> <span class="n">ambient</span><span class="o">.</span><span class="n">Profile</span><span class="p">(</span><span class="n">ctd_file</span><span class="p">,</span> <span class="n">chem_names</span><span class="o">=</span><span class="s1">&#39;all&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Once the CTD data are loaded as an <cite>ambient.Profile</cite> object, a
<cite>single_bubble_model</cite> object can be initialized:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">spm</span> <span class="o">=</span> <span class="n">stratified_plume_model</span><span class="o">.</span><span class="n">Model</span><span class="p">(</span><span class="n">ctd</span><span class="p">)</span>
</pre></div>
</div>
<p>The initial conditions for the release include the depth and discharge
characteristics.  A few are universal to the simulation and should be
specified right away:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">z0</span> <span class="o">=</span> <span class="mf">1000.</span>        <span class="c1"># release depth (m)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">R</span> <span class="o">=</span> <span class="mf">0.15</span>          <span class="c1"># radius of release region (m)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">T0</span> <span class="o">=</span> <span class="mf">273.15</span> <span class="o">+</span> <span class="mf">30.</span> <span class="c1"># temperature of released fluids (K)</span>
</pre></div>
</div>
<p>The remaining initial conditions are the dispersed phases that make up the
plume.  These should be passed to the <cite>stratified_plume_model.Model</cite>
object as a list of <cite>stratified_plume_model.Particle</cite> objects. First, open an
empty list, then create <cite>stratified_plume_model.Particle</cite> objects and append
them to the list.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">disp_phases</span> <span class="o">=</span> <span class="p">[]</span>
</pre></div>
</div>
<div class="section" id="gas-bubbles">
<h3>Gas Bubbles<a class="headerlink" href="#gas-bubbles" title="Permalink to this headline">¶</a></h3>
<p>For a blowout, we might expect both gas and oil.  Here, we create a few
gas bubbles to add to the simulation.  The first step is to create a <cite>dbm</cite>
particle object.  In this case, we choose a dissolvable particle of natural
gas:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">composition</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;methane&#39;</span><span class="p">,</span> <span class="s1">&#39;ethane&#39;</span><span class="p">,</span> <span class="s1">&#39;propane&#39;</span><span class="p">,</span> <span class="s1">&#39;oxygen&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mol_frac</span> <span class="o">=</span> <span class="p">[</span><span class="mf">0.93</span><span class="p">,</span> <span class="mf">0.05</span><span class="p">,</span> <span class="mf">0.02</span><span class="p">,</span> <span class="mf">0.0</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">gas</span> <span class="o">=</span> <span class="n">dbm</span><span class="o">.</span><span class="n">FluidParticle</span><span class="p">(</span><span class="n">composition</span><span class="p">)</span>
</pre></div>
</div>
<p>Next, we have to get the mass of each component in a single bubble and the
total bubble flux.  Two helper functions are provided in the <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code>
model.  These are <cite>stratified_plume_model.particle_from_Q</cite> and
<cite>stratified_plume_model.particle_from_mb0</cite>.  The former function is more
applicable to reservoir aeration plumes; the latter for a blowout.  In any
case, neither function is necessary as long as you can initialize a
<cite>stratified_plume_model.Particle</cite> object.  Here, we use the function that
is based on the mass flux and create six different sized bubbles:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># Initial bubble diameter (m)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">de</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.04</span><span class="p">,</span> <span class="mf">0.03</span><span class="p">,</span> <span class="mf">0.02</span><span class="p">,</span> <span class="mf">0.01</span><span class="p">,</span> <span class="mf">0.0075</span><span class="p">,</span> <span class="mf">0.005</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Total mass flux (kg/s) of gas in each bubble size class</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m0</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.5</span><span class="p">,</span> <span class="mf">1.5</span><span class="p">,</span> <span class="mf">2.5</span><span class="p">,</span> <span class="mf">3.5</span><span class="p">,</span> <span class="mf">1.5</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">]</span> <span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Associate spreading ratio (--)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lambda_1</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.75</span><span class="p">,</span> <span class="mf">0.8</span><span class="p">,</span> <span class="mf">0.85</span><span class="p">,</span> <span class="mf">0.9</span><span class="p">,</span> <span class="mf">0.9</span><span class="p">,</span> <span class="mf">0.95</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Append to the disp_phases list</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">de</span><span class="p">)):</span>
<span class="go">        disp_phases.append(stratified_plume_model.particle_from_mb0(ctd,</span>
<span class="go">            z0, gas, mol_frac, m0[i], de[i], lambda_1[i], T0))</span>
</pre></div>
</div>
</div>
<div class="section" id="oil-droplets">
<h3>Oil Droplets<a class="headerlink" href="#oil-droplets" title="Permalink to this headline">¶</a></h3>
<p>Following the same procedure as for the gas but with different equations of
state, liquid droplets can be added to the simulation. Start, by defining a
new set of equations of state. Here, we assume a non-dissolving oil phase:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">composition</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;inert&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rho_o</span> <span class="o">=</span> <span class="mf">890.</span>     <span class="c1"># density in kg/m^3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">gamma</span> <span class="o">=</span> <span class="mf">30.</span>      <span class="c1"># API gravity in deg API</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">beta</span> <span class="o">=</span> <span class="mf">0.0007</span>    <span class="c1"># thermal expansion coefficient in K^(-1)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">co</span> <span class="o">=</span> <span class="mf">2.90075e-9</span>  <span class="c1"># isothermal compressibility coefficient in Pa^(-1)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">oil</span> <span class="o">=</span> <span class="n">dbm</span><span class="o">.</span><span class="n">InsolubleParticle</span><span class="p">(</span><span class="kc">True</span><span class="p">,</span> <span class="kc">True</span><span class="p">,</span> <span class="n">rho_o</span><span class="p">,</span> <span class="n">gamma</span><span class="p">,</span> <span class="n">beta</span><span class="p">,</span> <span class="n">co</span><span class="p">)</span>
</pre></div>
</div>
<p>Then, define the droplet characteristics and append them to the
<code class="docutils literal notranslate"><span class="pre">disp_phases</span></code> list as we did for the gas bubbles. Note that all particles go
in the same list and could be in any order:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">de</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.02</span><span class="p">,</span> <span class="mf">0.01</span><span class="p">,</span> <span class="mf">0.0075</span><span class="p">,</span> <span class="mf">0.005</span><span class="p">,</span> <span class="mf">0.003</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m0</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">1.</span><span class="p">,</span> <span class="mf">2.5</span><span class="p">,</span> <span class="mf">5.</span><span class="p">,</span> <span class="mf">1.</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lambda_1</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.85</span><span class="p">,</span> <span class="mf">0.90</span><span class="p">,</span> <span class="mf">0.95</span><span class="p">,</span> <span class="mf">0.95</span><span class="p">,</span> <span class="mf">1.</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">de</span><span class="p">)):</span>
<span class="go">        disp_phases.append(stratified_plume_model.particle_from_mb0(ctd,</span>
<span class="go">            z0, oil, mol_frac, m0[i], de[i], lambda_1[i], T0))</span>
</pre></div>
</div>
</div>
<div class="section" id="run-the-simulation">
<h3>Run the Simulation<a class="headerlink" href="#run-the-simulation" title="Permalink to this headline">¶</a></h3>
<p>At this point, all of the initial conditions are defined, and we can run
the simulation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">max_iterations</span> <span class="o">=</span> <span class="mi">15</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">err_tolerance</span> <span class="o">=</span> <span class="mf">0.2</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">output_dz_max</span> <span class="o">=</span> <span class="mf">10.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">spm</span><span class="o">.</span><span class="n">simulate</span><span class="p">(</span><span class="n">disp_phases</span><span class="p">,</span> <span class="n">z0</span><span class="p">,</span> <span class="n">R</span><span class="p">,</span> <span class="n">maxit</span><span class="o">=</span><span class="n">max_iterations</span><span class="p">,</span>
<span class="go">        toler=err_tolerance, delta_z = output_dz_max)</span>
</pre></div>
</div>
<p>The above command will echo progress to the screen and produce a plot of the
state space for each successive iteration.</p>
</div>
<div class="section" id="saving-model-results">
<h3>Saving Model Results<a class="headerlink" href="#saving-model-results" title="Permalink to this headline">¶</a></h3>
<p>The simulation results can be saved to a netCDF file, which can be used to
continue analysis within the TAMOC Python package, or an ascii text file for
importing to another analysis package, such as Excel or Matlab. To save the
data, specify a base output name with relative file path, a path to the CTD
data, and a description of the CTD data:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f_name</span> <span class="o">=</span> <span class="s1">&#39;../test/output/ntbk_blowout&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_description</span> <span class="o">=</span> <span class="s1">&#39;CTD data from Brooks McCall in file&#39;</span> <span class="o">+</span> \
<span class="go">                      &#39;./test/output/test_BM54.nc&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">spm</span><span class="o">.</span><span class="n">save_sim</span><span class="p">(</span><span class="n">f_name</span> <span class="o">+</span> <span class="s1">&#39;.nc&#39;</span><span class="p">,</span> <span class="n">ctd_file</span><span class="p">,</span> <span class="n">ctd_description</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">spm</span><span class="o">.</span><span class="n">save_txt</span><span class="p">(</span><span class="n">f_name</span> <span class="o">+</span> <span class="s1">&#39;ASCII&#39;</span><span class="p">,</span> <span class="n">ctd_file</span><span class="p">,</span> <span class="n">ctd_description</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Texas A&M Oil spill / Outfall Calculator</a></h1>








<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../user_manual.html">TAMOC User Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../unit_tests.html">Unit Tests</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../readme.html">Read Me File</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release.html">Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license.html">License</a></li>
</ul>

<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="../index.html">Documentation overview</a><ul>
  <li><a href="../user_manual.html">TAMOC User Manual</a><ul>
      <li>Previous: <a href="../scripts/sbm/seep_bubble.html" title="previous chapter">seep_bubble</a></li>
      <li>Next: <a href="../scripts/spm/lake_bub.html" title="next chapter">lake_bub</a></li>
  </ul></li>
  </ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" />
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>$('#searchbox').show(0);</script>








        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy;2020, Scott A. Socolofsky.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
      |
      <a href="../_sources/guides/spm.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    

    
  </body>
</html>